Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support


Apple IIGS
#48:    All About AlertWindow

Written by:    Dan Oliver & Keith Rollin                         November 1988

This Technical Note documents a new call in the Window Manager which eases the 
creation of Alert windows.
_____________________________________________________________________________

Window Manager version 2.2, which is available on Apple IIGS System Disk 3.2 
and later, includes a new call, AlertWindow.  This call takes three parameters 
which are used to create a dialog box with text, buttons, and an optional 
icon.

AlertWindow works by taking a pointer to an "alert string."  This alert string 
defines the size and location of the alert window, specifies what icon (if 
any) it uses, defines the text it displays, and indicates the number of 
buttons and their names which it displays.

The alert string is a very powerful and complicated structure to be able to 
specify all of this information, and it gets even more powerful with the added 
capability of "substitution strings."  Substitution strings work in a manner 
similar to ParamText substitutions; certain sections of the text are 
designated as variables to b e replaced with other text when you display the 
dialog.


The Call

AlertWindow ($590E)

    input:     WORD -    Space for result.
               WORD -    String flag. 0 if substitution strings are C-type or 
                         NULL terminated, 1 if Pascal-type.
               LONG -    Pointer to substitution string array, anything if no 
                         substitutions are to be made.
               LONG -    Pointer to alert string.
    output:    WORD -    Button number that was selected where 0 is the first 
                         button title in the alert string, 1 is the next button 
                         title, and 2 is the third.


The Format of the Alert String

Size Character

The first character of the alert string is the size character, which indicates 
the size of the alert window.  The character can be ASCII 1 - 9 to indicate 
any one of nine standard alert window sizes.  The goal of standard sizes is to 
have alert windows that can contain the same amount of message text in 320 
mode or 640 mode, without changing the size.  However, making this happen may 
require some careful message and button text composition.

Size Character    Approximate Maximum # of Characters
    1                           30
    2                           60
    3                          110
    4                          175
    5                          110
    6                          150
    7                          200
    8                          250
    9                          300

The following table shows the dimensions of the standard alert windows.  This 
information is to give an idea of the size of each window.  Application code 
should not rely on the exact widths, heights, or position of standard windows.  
If an application needs an exact window size, then it can specify zero as the 
size character and use the next 8 bytes as 4 word-sized integers which specify 
the rectangle of the window.

Character    Height 320    Width 320    Height 640    Width 640
    1            46           152           46           200
    2            62           176           54           228
    3            62           252           62           300
    4            90           252           72           352
    5            54           252           46           400
    6            62           300           54           452
    7            80           300           62           500
    8           108           300           72           552
    9           134           300           80           600
    0    (Character followed by 4 integers that represent size and position.)

Icon Number

The next character is the icon number.  The icon number can be 0 - 9 where:

    0 =        No icon.
    1 =        custom icon, followed by:
               LONG    Pointer to image data.
               WORD    Number of bytes image data is wide.
               WORD    Number of scan lines image data is high.
    2 =        Stop icon.
    3 =        Note icon.
    4 =        Caution icon.
    5 =        Disk icon.
    6 =        Disk swap icon.
    7 - 9 =    Reserved - do not use.

Separator Character

The next character is a separator character.  The separator can be any 
character you would like and cannot appear in the message text or button 
strings.  The separator is used to separate the message from the first button 
string and each button string from each other.  For purposes of 
standardization the slash (/) might be a good choice.

Message Text

Following the separator character is the message text.  Any characters allowed 
by LETextBox2 are allowed in the message text.  See Special Characters below 
for additional functions of message text.  The total size of the message text, 
after substitution of strings, is limited to 1000 characters.

Button Strings

The first character after the separator character following the message text 
is the beginning of the first button's title.  The title can be followed with 
either another separator character and button title or a string termination 
character (i.e., zero (0)) to end the alert string.  A total of three button 
titles may be included at the end of the alert string.  These buttons will be 
evenly spaced and centered at the bottom of the alert window.  The width of 
each button will be the same size and will be set according to the widest 
button title.  The total size of button text, after substitution of strings, 
is limited to 80 characters.

Termination of Alert String

A zero (0) comes after the last button title to end the alert string.


The Substitution Strings

The message text and button strings can contain special characters that will 
be replaced with substitution strings when you display the alert window.

Special Characters

The following special characters can be embedded in the message text and 
button strings of an alert.  If you want the special character itself to 
appear in the body of the text, enter it twice in the string.

    ^        If a caret (^) is the first character in a button string, 
             the button is the default button.  The default button is the 
             the button selected if the user presses the Return key or 
             the Enter key on the keyboard.  This button also has a bold 
             outline on the screen.  Only one button can be the default 
             button.  After the caret, the button title must follow like 
             any other title (including other special characters).

             Note:    If the caret is to appear in the message text, 
             it must be entered twice, side-by-side.  A single 
             caret in message text has no effect and is deleted 
             from the message.

    #        Substitute with a standard string.  The pound sign (#) must 
             be followed by an ASCII character.  Characters 0 - 6 can be 
             used (7 - 9 are reserved and should not be used) where:

             #0 will be substituted with OK
             #1 will be substituted with Cancel
             #2 will be substituted with Yes
             #3 will be substituted with No
             #4 will be substituted with Try Again
             #5 will be substituted with Quit
             #6 will be substituted with Continue

    *        Substitute with the given string.  The asterisk (*) followed 
             by ASCII character in the range 0 - 9 denotes that a 
             substitution string should be inserted at that point.  The 
             asterisk and the following character will be replaced by the 
             corresponding string in the substitution array.  A pointer 
             to the substitution array is one of the parameters passed to 
             AlertWindow and is defined as an array of LONG pointers 
             where:

             LONG[0]    Pointer to the string that will substitute for *0.
             LONG[1]    Pointer to the string that will substitute for *1.
             LONG[2]    Pointer to the string that will substitute for *2.
             LONG[3]    Pointer to the string that will substitute for *3.
             LONG[4]    Pointer to the string that will substitute for *4.
             LONG[5]    Pointer to the string that will substitute for *5.
             LONG[6]    Pointer to the string that will substitute for *6.
             LONG[7]    Pointer to the string that will substitute for *7.
             LONG[8]    Pointer to the string that will substitute for *8.
             LONG[9]    Pointer to the string that will substitute for *9.

             Substitution strings can be a C-type (NULL-terminated), 
             Pascal-type (a string prefixed with a length byte), or 
             Return-terminated.  NULL and Return-terminated strings are 
             selected by passing 0 to AlertWindow as the string flag.  
             Pascal strings are selected by passing 1.

             Elements do not need to be defined if they are not 
             referenced in the alert.


Examples

Here are some examples of alert strings that can be passed to AlertWindow in 
APW 65816 assembler syntax.

A simple alert string:

          dc    c'13/Text of Message/Button 1',il'0'---
                   \     \              \              \
   Size 50 high     Icon  Message        Button Title   Zero terminates alert.
    by 200 wide.

                  |--------------------------------------|
                  | #################################### |
                  | #   ______                         # |
                  | #  | Note |    Text of Message     # |
                  | #  | Icon |                        # |
                  | #  |______|                        # |
                  | #                                  # |
                  | #               _____________      # |
                  | #              /             \     # |
                  | #              |   Button 1  |     # |                                                         
                  | #              \_____________/     # |
                  | #                                  # |
                  | #################################### |
                  |--------------------------------------|

A more complex alert string:

          dc   c'51/This is the *0 of *3 alert *2*1 and'
          dc   c'standard text called "#4" /'
          dc   c'^#0,Really/*4/Yo!',il'13'


    |-----------------------------------------------------------------------|
    | ##################################################################### |
    | #   ______                                                          # |
    | #  | Note |    This is the message text of an alert window and      # |
    | #  | Icon |    standard text called "Try Again."                    # |
    | #  |______|                                                         # |
    | #                                                                   # |
    | #           _____________      _____________      _____________     # |
    | #          /             \    /             \    /             \    # |
    | #          | OK, Really  |    |   Door #2   |    |      Yo!    |    # |                                                         
    | #          \_____________/    \_____________/    \_____________/    # |
    | #                                                                   # |
    | ##################################################################### |
    |-----------------------------------------------------------------------|
                                                               

          Where substitution array =
                          dc   i4'sub0,sub1,sub2,sub3,sub4'
                  sub0    dc   c'message text',il'0'
                  sub1    dc   c'dow',il'0'
                  sub2    dc   c'win',il'13'
                  sub3    dc   c'an',il'0'
                  sub4    dc   c'Door #2',il'0'


